<html>
<head>
<title>User Manual: Starting Out</title>
<link href="./page.css" rel="stylesheet" type="text/css"/>
<link href="./olive.css" rel="stylesheet" type="text/css"/>
<link href="./manual.css" rel="stylesheet" type="text/css"/>
</head>
<body>

<h1>1. Getting Started</h1>
<p>
Prev | <a href="index.html">Index</a> | <a href="news.html">Next</a> (Reading News)
</p>
<hr/>


<h2 id="s10">1.1 Installation</h2>
<p>
  Installing Olive is a simple, streamlined process (so long as you're
  not on OS X). After unpacking the tarball, <code>cd</code> into the
  resultant directory and run '<code>make</code>'.
</p>
<p class='warn'>
  NB: If you are on a BSD system, run '<code>gmake</code>' instead of
  '<code>make</code>'.
</p>
<p>
  This will run a dependancy check and report the results. You may
  see:
</p>
<pre><code>  mdxi@fornax:~/olive$ make
  Checking for dependancies...looks good.
  mdxi@fornax:~/olive$ 
</code></pre>
<p>
  but chances are that you'll see something more like this:
</p>
<pre><code>  mdxi@fornax:~/olive$ make
  Checking for dependancies...Required modules not found:
      Config::YAML
      DBD::SQLite
      XML::Simple
  make: *** [olive] Error 1
  mdxi@fornax:~/olive$ 
</code></pre>
<p>
  The easiest thing to do, should you be missing modules, is to let
  the <code>cpan</code> script install Bundle::Olive for you. This
  will install all of Olive's dependancies (and all of <i>their</i>
  dependancies), all at once. If, for whatever reason, you don't wish
  to do this, install the list of modules reported as missing by
  whatever mechanism you wish. The effect is the same.
</p>
<p>
  With all deps installed, you may want to look at the top of the
  Makefile, where you'll find this:
</p>
<pre><code>  PREFIX  = /usr/local
  BINDIR  = $(PREFIX)/bin
  LIBDIR  = $(PREFIX)/share/olive
  DOCDIR  = $(PREFIX)/share/doc/olive
</code></pre>
<p>
  If this (very standard) layout isn't to your liking, modify it to
  suit you. Now it's time for the actual install.
</p>
<pre><code>  mdxi@fornax:~/olive$ sudo make install
  Checking for dependancies...looks good.
  Prepping for install.
  Creating install directories.
  Installing Olive.
  Cleaning up.
  Done. Now run /usr/local/bin/olive to get started!
</code></pre>
<p>
  That's all there is to it.
</p>



<h2 id="s20">1.2 OPML Import</h2>
<p>
  If you have been using NetNewsWire or Bloglines, Olive can import
  OPML files exported by them, sparing you from having to manually add
  those feeds. This would be a good time to do that.
</p>
<p>
  Just run '<code>olive [OPML_FILE]</code>' and the import process will
  proceed.
</p>
<pre><code> mdxi@fomalhaut:~$ ./olive bloglines.opml 
 Olive starting up.
 Loading modules.
 Initialising objects and data.
 Beginning OPML import.
 Descending into HTML-CSS-DTHML-Javascript...
 Descending into News...
 Descending into Of Interest...
 Descending into People...
 Descending into Perl...
 Descending into User Groups...
 Descending into VIm...
 71 of 75 feeds imported
 See ~/.olive/errors.log for more information

 mdxi@fomalhaut:~$ cat ~/.olive/errors.log
 -- Starting up at 2006-00-04T19:47:15 --
 The nick 'The Daily Herald' is in use or reduces to a nick which is in use (http://www.harktheherald.com/feed_letters.php).
 The nick 'The Daily Herald' is in use or reduces to a nick which is in use (http://www.harktheherald.com/feed_top.php).
 The nick 'The Daily Herald' is in use or reduces to a nick which is in use (http://www.harktheherald.com/feed_opinion.php).
 The nick 'Jeremy Zawodny's' is in use or reduces to a nick which is in use (http://jeremy.zawodny.com/blog/rss2.xml).

 mdxi@fomalhaut:~$
</code></pre>
<p>
  This can be done at any time (but shouldn't be done when another
  copy of Olive is running).
</p>
<p>
  As the example above shows, any feeds in the OPML file which are
  already found in the Olive feed list will be rejected and a notice
  will be written to the error log. Feeds whose descriptions cause
  collisions with existing feeds will be similarly rejected.
</p>



<h2 id="s30">1.3 First Run</h2>
<p>
  The first thing you'll see is a splash screen welcoming you to Olive
  and telling you how to get to the help popup. This will only be
  shown the first time you run Olive.
</p>
<p>
  Once the welcome message is cleared, you'll be looking at the main
  Olive interface. If you have already imported a feed list, the feeds
  will be polled and processed and you'll be ready to go. If not, your
  screen will be mostly blank and you'll need to add some feeds. You
  can do this by pressing '<code>C-a</code>' and filling in values in
  the dialogue which pops up. You will also want to set your external
  browser command in the Options panel. Press '<code>C-o</code>' to
  invoke that panel and see <a href="options.html#s50">Section 3.5</a>
  for more information.
</p>
<p>
  The top half of the screen is occupied by the List Pane, where the
  list of available stories is displayed. Use the up and down arrow
  keys to navigate it and the <code>Enter</code> key to select a
  story. Once selected, the content of the story will be displayed in
  the Story Pane, at the bottom of the screen (if you need to scroll
  this pane, use the <code>Spacebar</code> to page the story text down
  and the '<code>-</code>' key to page it up).
</p>
<p>
  To exit Olive, press '<code>Q</code>'.
</p>
<p>
  There are more advanced functionality and alternate keys
  available (that's what the rest of this manual is for) but those are
  the basics.
</p>



<h2 id="s40">1.4 The Help System</h2>
<p>
  As long as there isn't a dialog on screen, you can press
  '<code>h</code>' or '<code>?</code>' to access the help popup, which
  contains a list of keybindings and some other information.
</p>
<p>
  More complete help is found in this manual, which can be accessed
  from within Olive by pressing '<code>C-n</code>'. This will launch
  an external browser with the manual index loaded.
</p>


<h2 id="s50">1.5 Feedback and Bug Reports</h2>
<p>
  You
  can <a href="http://trac.collapsar.net/olive/trac.cgi/report/3">view
  existing bug reports</a>
  and <a
  href="http://trac.collapsar.net/olive/trac.cgi/newticket">file new
  ones</a> at the Olive Trac wiki.  If that doesn't work for you, or
  if you just have comments or questions, send them to me at
  &lt;<code>mdxi@cpan.org</code>&gt;
</p>

<hr/>
<p>
Prev | <a href="index.html">Index</a> | <a href="news.html">Next</a> (Reading News)
</p>
<hr/>
<p>
$Id: start.html 436 2007-04-30 13:09:01Z mdxi $
</p>
</body>
</html>
